import importlib
import importlib.util
import inspect
import sys
import warnings
from abc import ABC, abstractmethod
from pathlib import Path
from typing import TYPE_CHECKING, Any, Type
from .pipeline import PipeModule

namespace: Any
source: Any

def register_module(module_class: Type[Any], silent: bool = False) -> Any:
    """
    Register a user-defined PipeModule class.
    
    Args:
        module_class: The PipeModule subclass to register
        silent: If True, suppresses printed messages (default: False)
    
    Returns:
        None
    
    Example:
        ```python
        # In your custom module file (e.g., my_modules/custom_module.py)
        from gdi.modules.pipeline import PipeModule, status_manage
    
        @status_manage
        class MyCustomModule(PipeModule):
            # Your module implementation
            pass
    
        # In your main file where you want to register it
        from gdi.modules.nameSpace import register_module
        from my_modules.custom_module import MyCustomModule
    
        # Register your custom module (with or without messages)
        register_module(MyCustomModule)  # With messages
        register_module(MyCustomModule, silent=True)  # Without messages
        ```
    """
    ...
def register_modules_from_file(file_path: Any, silent: bool = False) -> Any:
    """
    Register all PipeModule subclasses from a specific Python file.
    
    Args:
        file_path: Path to the Python file containing module definitions
        silent: If True, suppresses printed messages (default: False)
    
    Returns:
        None
    
    Example:
        ```python
        from gdi.modules.nameSpace import register_modules_from_file
    
        # With messages
        register_modules_from_file("./my_modules/custom_module.py")
    
        # Without messages
        register_modules_from_file("./my_modules/custom_module.py", silent=True)
        ```
    """
    ...
def register_modules_from_directory(directory_path: Any, silent: bool = False) -> Any:
    """
    Scan a directory and register all PipeModule subclasses found.
    
    Args:
        directory_path: Path to the directory containing module definitions
        silent: If True, suppresses printed messages (default: False)
    
    Returns:
        None
    
    Example:
        ```python
        from gdi.modules.nameSpace import register_modules_from_directory
    
        # With messages
        register_modules_from_directory("./usermodules")
    
        # Without messages
        register_modules_from_directory("./usermodules", silent=True)
        ```
    """
    ...
def discover_modules_in_directory(package_name: str, silent: bool = False) -> dict[str, Any]:
    """
    Dynamically discover all PipeModule subclasses.
    
    Args:
        package_name: The name of the package to scan ('gdi.modules' or 'gdisdk.modules')
        silent: If True, suppresses printed messages (default: False)
    
    Returns:
        A dictionary mapping class names to class objects
    """
    ...
def get_module_namespace(silent: bool = False) -> dict[str, Any]:
    """
    Get all PipeModule subclasses from the gdi.modules or gdisdk.modules package and user registry.
    
    Args:
        silent: If True, suppresses printed messages (default: False)
    
    Returns:
        A dictionary mapping class names to class objects
    """
    ...
def load_local_function_provider(file_path: Any, class_name: str, debug_mode: bool = False) -> LocalFunctionProvider:
    """
    Load a LocalFunctionProvider instance from a Python file.
    
    This function dynamically loads a LocalFunctionProvider subclass from a Python file
    and instantiates it with the provided context.
    
    Parameters
    ----------
    file_path : str | Path
        The path to the Python file containing the LocalFunctionProvider subclass.
    class_name : str
        The name of the LocalFunctionProvider subclass to load.
    debug_mode : bool, default False
        If True, provides detailed error messages including full tracebacks.
        If False, provides concise error messages for production use.
    
    Returns
    -------
    LocalFunctionProvider
        An instance of the LocalFunctionProvider subclass
    
    Example
    -------
    ```python
    # Load a provider instance from an external file
    provider = load_local_function_provider('my_providers.py', 'MyCustomProvider')
    result = provider.run_function()
    
    # For debugging with detailed error information
    provider = load_local_function_provider('my_providers.py', 'MyCustomProvider', debug_mode=True)
    ```
    
    Raises
    ------
    FileNotFoundError
        If the specified file does not exist
    ImportError
        If there are import issues with the file
    SyntaxError
        If the file contains syntax errors
    AttributeError
        If the specified class is not found in the file
    TypeError
        If the specified name is not a class or not a LocalFunctionProvider subclass
    RuntimeError
        For other execution errors
    
    Notes
    -----
    This function requires a valid local function file and will raise specific exceptions
    for different failure modes. All errors are fatal since the pipeline depends on the
    local function working correctly.
    
    The error handling provides:
    - Detailed syntax error information with line numbers and position
    - Specific exception types for different failure modes
    - Full traceback information for debugging when debug_mode=True
    - Concise error messages for production use when debug_mode=False
    """
    ...
def get_local_function(module: Any, function_name: str, pipeline_local_functions_path_first: bool = True, debug_mode: bool = False) -> Any:
    """
    Get the local function of the module.
    
    Parameters
    ----------
    module : PipeModule
        The module to get the local function.
    
    function_name : str
        The name of the function to get.
    
    pipeline_local_functions_path_first : bool, default: True
        If True, the 'local_functions_path' attribute of the pipeline will be used to find the local functions path first.
        If False, the module's attributes 'local_functions_path' will be used to find the local functions path first.
    
    debug_mode : bool, default False
        If True, provides detailed error messages including full tracebacks when loading fails.
        If False, provides concise error messages for production use.
    
    Returns
    -------
    LocalFunctionProvider | None
        The instance of the LocalFunctionProvider subclass, or None if getting fails
    """
    ...

class LocalFunctionProvider(ABC):
    """
    Abstract base class for local function providers.
    
    This class serves as a blueprint for creating custom local function providers.
    Subclasses must implement the `get_function` method to generate appropriate
    function objects based on the context.
    
    Example
    -------
    ```python
    class MyCustomProvider(LocalFunctionProvider):
        def get_function(self) -> Callable:
            filter_by = self.context.get('filter_by')
    
            if filter_by == 'status':
                return RangeModel(
                    vtype="str",
                    title="Status",
                    choices=("Active", "Pending", "Completed"),
                    default="Active"
                )
            return RangeModel(vtype="str", title="Value", default="")
    ```
    """
    def __init__(self):
        """
        Initialize with optional context.
        
        Parameters
        ----------
        context : dict[str, Any], optional
            Initial context dictionary containing information about the current state.
        """
        ...
    def update_context(self, context: dict[str, Any]) -> Any:
        """
        Update the context dictionary with new values.
        
        Parameters
        ----------
        context : Dict[str, Any]
            New context values to update
        """
        ...
    def run_function(self, **kwargs) -> Any:
        """
        Run the function based on the context.
        
        This method must be implemented by subclasses to generate an appropriate
        function object based on the current context.
        
        Returns
        -------
        Any
            The result of the function execution
        """
        ...
